import { RadioGroup } from 'bumbag';

# RadioGroup

A `<RadioGroup>` can be used to render a set of [Radio components](/form/radio).

## Import

```jsx
import { RadioGroup } from 'bumbag'
```

## Usage

```jsx-live
<RadioGroup
  name="weather"
  options={[
    { label: 'Sunny', value: 'sunny' },
    { label: 'Windy', value: 'windy' },
    { label: 'Overcast', value: 'overcast' }
  ]}
/>
```

### Fields

You can also use the `<RadioGroupField>` component, which internally has a [FieldWrapper](/form/field-wrapper) to wrap form controls such as labels, hint text and validation text.

It accepts a combination of [RadioGroup props](/form/radio-group/#props) and [FieldWrapper props](/form/field-wrapper/#props).

```jsx-live
<RadioGroupField
  label="What's the weather?"
  name="weather5"
  options={[
    { label: 'Sunny', value: 'sunny' },
    { label: 'Windy', value: 'windy' },
    { label: 'Overcast', value: 'overcast' }
  ]}
/>
```

### Horizontal group

```jsx-live
<RadioGroup
  orientation="horizontal"
  name="weather2"
  options={[
    { label: 'Sunny', value: 'sunny' },
    { label: 'Windy', value: 'windy' },
    { label: 'Overcast', value: 'overcast' }
  ]}
/>
```

### Disabled

You can disable a radio group with the `disabled` prop. If you only want to disable one option, add the `disabled: true` attribute to the option.

```jsx-live
<RadioGroup
  name="weather"
  options={[
    { label: 'Sunny', value: 'sunny' },
    { label: 'Windy', value: 'windy', disabled: true },
    { label: 'Overcast', value: 'overcast' }
  ]}
/>
```

```jsx-live
<RadioGroup
  disabled
  name="weather"
  options={[
    { label: 'Sunny', value: 'sunny' },
    { label: 'Windy', value: 'windy' },
    { label: 'Overcast', value: 'overcast' }
  ]}
/>
```

### States

A RadioGroup can use different states (as per palette) such as `danger`, `success` and `warning`.

```jsx-live
<RadioGroup
  state="danger"
  name="weather4"
  options={[
    { label: 'Sunny', value: 'sunny' },
    { label: 'Windy', value: 'windy' },
    { label: 'Overcast', value: 'overcast' }
  ]}
/>
```

### Default value

Specify a default checked value with the `defaultValue` prop.

```jsx-live
<RadioGroup
  defaultValue="overcast"
  name="weather5"
  options={[
    { label: 'Sunny', value: 'sunny' },
    { label: 'Windy', value: 'windy' },
    { label: 'Overcast', value: 'overcast' }
  ]}
/>
```

### Controlled Usage

The previous examples are examples of uncontrolled usage. To control the value yourself, use a combination of `onChange` and `value`.

Note: Do not use `defaultValue` with controlled inputs!

```function-live
function Example() {
  const [value, setValue] = React.useState('');

  return (
    <RadioGroup
      options={[
        { label: 'Sunny', value: 'sunny' },
        { label: 'Windy', value: 'windy' },
        { label: 'Overcast', value: 'overcast' }
      ]}
      onChange={e => setValue(e.target.value)}
      value={value}
    />
  )
}
```

## Accessibility

The `<RadioGroup>` component follows the [WAI ARIA RadioGroup Pattern](https://www.w3.org/TR/wai-aria-practices/#radiogroup).

#### Patterns

- The outer wrapper of the group has a role of `radiogroup`.
- The radio has a role of `radio`.
- Pressing <Key>Tab</Key> and <Key>Shift</Key> + <Key>Tab</Key> moves focus in and out of the radio group.
- Pressing <Key>Space</Key> checks the selected radio button.
- Pressing <Key>Up</Key>, <Key>Down</Key>, <Key>Left</Key> or <Key>Right</Key> will move the current selection to the next or previous item.

#### References

- [WAI ARIA RadioGroup Pattern](https://www.w3.org/TR/wai-aria-practices/#radiogroup)

## Props

### RadioGroup Props

<!-- Automatically generated -->

**<Code fontSize="150" marginRight="major-1">defaultValue</Code>** <Code fontSize="100" palette="primary">string</Code> 

Default value of the radio group

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">disabled</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Disables the radio group

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">name</Code>** <Code fontSize="100" palette="primary">string</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">orientation</Code>** <Code fontSize="100" palette="primary">&#34;horizontal&#34; | &#34;vertical&#34;</Code> 

Are the radio inputs layed out horizontally?

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">options</Code>** <Code fontSize="100" palette="primary">RadioProps[]</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Radio group options

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">spacing</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">state</Code>** <Code fontSize="100" palette="primary">string</Code> 

State of the radio group. Can be any color in the palette.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">value</Code>** <Code fontSize="100" palette="primary">string</Code> 

Controlled value of the radio group

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">onChange</Code>** <Code fontSize="100" palette="primary">(event: FormEvent&#60;HTMLInputElement&#62;) =&#62; void</Code> 

Function to invoke when radio group has changed

<Divider marginTop="major-2" marginBottom="major-2" />

### RadioGroupField Props

<!-- Automatically generated -->

**<Code fontSize="150" marginRight="major-1">radioGroupProps</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`Pick<BoxProps, "unstable_system"
  | "top"
  | "right"
  | "bottom"
  | "left"
  | "children"
  | "defaultChecked"
  | "defaultValue"
  | "suppressContentEditableWarning"
  | "suppressHydrationWarning"
  | ... 649 more ...
  | "themeKey"> & LocalRadioGroupProps`}
</Code>

Additional props for the RadioGroup component

<Divider marginTop="major-2" marginBottom="major-2" />

<details><Box use="summary" marginBottom="major-2">Inherits <strong><code>RadioGroup</code></strong> props</Box>

**<Code fontSize="150" marginRight="major-1">defaultValue</Code>** <Code fontSize="100" palette="primary">string</Code> 

Default value of the radio group

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">disabled</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Disables the radio group

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">name</Code>** <Code fontSize="100" palette="primary">string</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">orientation</Code>** <Code fontSize="100" palette="primary">&#34;horizontal&#34; | &#34;vertical&#34;</Code> 

Are the radio inputs layed out horizontally?

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">options</Code>** <Code fontSize="100" palette="primary">RadioProps[]</Code> <Text marginLeft="major-1" fontSize="150" textTransform="uppercase" color="gray">Required</Text>

Radio group options

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">spacing</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">state</Code>** <Code fontSize="100" palette="primary">string</Code> 

State of the radio group. Can be any color in the palette.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">value</Code>** <Code fontSize="100" palette="primary">string</Code> 

Controlled value of the radio group

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">onChange</Code>** <Code fontSize="100" palette="primary">(event: FormEvent&#60;HTMLInputElement&#62;) =&#62; void</Code> 

Function to invoke when radio group has changed

<Divider marginTop="major-2" marginBottom="major-2" />

</details>
            

<details><Box use="summary" marginBottom="major-2">Inherits <strong><code>FieldWrapper</code></strong> props</Box>

**<Code fontSize="150" marginRight="major-1">children</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>
  | (({ elementProps }: { ...; }) => ReactNode)`}
</Code>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">description</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>`}
</Code>

Sets the description text of the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">hint</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>`}
</Code>

Sets the bottom hint text of the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">isOptional</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Sets the optional flag (and displays optional text) on the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">isRequired</Code>** <Code fontSize="100" palette="primary">boolean</Code> 

Sets the required flag (and a required astrix) on the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">label</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>`}
</Code>

Sets the label on the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">labelType</Code>** <Code fontSize="100" palette="primary">&#34;label&#34; | &#34;legend&#34;</Code> 

Sets the label type on the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">tooltip</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>`}
</Code>

Sets the tooltip of the field wrapper. Can be either a string, or a React component.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">tooltipTriggerComponent</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>`}
</Code>

Sets the tooltip trigger component.

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">validationText</Code>** <Code fontSize="100" palette="primary">string</Code> 

Sets the bottom validation text of the field wrapper.

<Divider marginTop="major-2" marginBottom="major-2" />

</details>
            

<details><Box use="summary" marginBottom="major-2">Inherits <strong><code>Box</code></strong> props</Box>

**<Code fontSize="150" marginRight="major-1">use</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`string
  | (ComponentClass<any, any> & { useProps: any; })
  | (FunctionComponent<any> & { useProps: any; })`}
</Code>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">className</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">alignX</Code>** <Code fontSize="100" palette="primary">&#34;right&#34; | &#34;left&#34; | &#34;center&#34;</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">alignY</Code>** <Code fontSize="100" palette="primary">&#34;top&#34; | &#34;bottom&#34; | &#34;center&#34;</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">variant</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">colorMode</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">overrides</Code>**  

<Code isBlock palette="primary" fontSize="150" padding="minor-1" marginBottom="major-2">
{`{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 96 more ...;
  Template?: TemplateThemeConfig;
}`}
</Code>

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">elementRef</Code>** <Code fontSize="100" palette="primary">((instance: any) =&#62; void) | RefObject&#60;any&#62;</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

**<Code fontSize="150" marginRight="major-1">themeKey</Code>** <Code fontSize="100" palette="primary">string</Code> 

<Divider marginTop="major-2" marginBottom="major-2" />

</details>
            

## Theming

 <Theme
  component={'RadioGroup'}
  options={[
    { label: 'Sunny', value: 'sunny' },
    { label: 'Windy', value: 'windy' },
    { label: 'Overcast', value: 'overcast' }
  ]}
  overrides={[
    'RadioGroup.styles.base',
    'Radio.styles.base',
    'Radio.Icon.styles.base',
    'Radio.Label.styles.base',
    'Radio.HiddenInput.styles.base'
  ]} />
